Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

CompressImage

The CompressImage function allows your application to compress a single-frame image that is currently stored as a pixel map structure.

pascal OSErr CompressImage (PixMapHandle src,
                                         const Rect *srcRect,
                                         CodecQ quality, CodecType cType,
                                         ImageDescriptionHandle desc,
                                         Ptr data);


src

Contains a handle to the image to be compressed. The image must be stored in a pixel map structure.

srcRect

Contains a pointer to a rectangle defining the portion of the image to compress.

quality

Specifies the desired compressed image quality. See "Compression Quality Constants" for valid values.

cType

Specifies a compressor type. You must set this parameter to a valid compressor type (see Table 3 for a list of the available compressor types).

desc

Contains a handle that is to receive a formatted image description structure. The Image Compression Manager resizes this handle for the returned image description structure. Your application should store this image description with the compressed image data.

data

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by the GetMaxCompressionSize function (described on GetMaxCompressionSize ). The Image Compression Manager places the actual size of the compressed image into the dataSize field of the image description structure referred to by the desc parameter. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that handle with this parameter (for details on StripAddress , see Inside Macintosh: Memory ).

FCompressImage

Like the CompressImage function, the FCompressImage function allows your application to compress a single-frame image that is currently stored as a pixel map structure ( PixMap ).

pascal OSErr FCompressImage (PixMapHandle src,
                                         const Rect *srcRect,
                                         short colorDepth, CodecQ quality,
                                         CodecType cType,
                                         CompressorComponent codec,
                                         CTabHandle ctable, CodecFlags flags,
                                         long bufferSize,
                                         ICMFlushProcRecordPtr flushProc,
                                         ICMProgressProcRecordPtr progressProc,
                                         ImageDescriptionHandle desc,
                                         Ptr data);


src

Contains a handle to the image to be compressed. The image must be stored in a pixel map structure.

srcRect

Contains a pointer to a rectangle defining the portion of the image to compress.

colorDepth

Specifies the depth at which the image is likely to be viewed. Compressors may use this as an indication of the color or grayscale resolution of the compressed image. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function (see "Getting Information About Compressor Components" for more information on the GetCodecInfo function).

quality

Specifies the desired compressed image quality. See "Compression Quality Constants" , for valid values.

cType

Specifies a compressor type. You must set this parameter to a valid compressor type (see Table 3 for a list of the available compressor types).

codec

Specifies a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCode

Choose the most accurate compressor of the specified type

bestCompressionCodec

Choose the compressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

If you set the codec parameter to anyCodec , the Image Compression Manager chooses the first compressor it finds of the specified type.

ctable

Contains a handle to a custom color lookup table. Your program may use this parameter to indicate a custom color lookup table to be used with this image. If the value of the colorDepth parameter is less than or equal to 8 and the custom color lookup table is different from that of the source pixel map (that is, the ctSeed field values differ in the two pixel maps), the compressor remaps the colors of the image to the custom colors. If you set the colorDepth parameter to 16, 24, or 32, the compressor stores the custom color table with the compressed image. The compressor may use the table to specify the best colors to use when displaying the image at lower bit depths. The compressor ignores the ctable parameter when colorDepth is set to 33, 34, 36, or 40. If you set this parameter to nil , the compressor uses the color lookup table from the source pixel map.

flags

Specifies flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on Image Compression Manager Function Control Flags , for information about CodecFlags fields. The following flag is available for this function:

codecFlagWasCompressed

Indicates to the compressor that the image to be compressed has been compressed before. This information may be useful to compressors that can compensate for the image degradation that may otherwise result from repeated compression and decompression of the same image. Set this flag to 1 to indicate that the image was previously compressed. Set this flag to 0 if the image was not previously compressed.

bufferSize

Specifies the size of the buffer to be used by the data-unloading function specified by the flushProc parameter. If you have not specified a data-unloading function, set this parameter to 0.

flushProc

Points to a data-unloading function structure. If there is not enough memory to store the compressed image, the compressor calls a function you provide that unloads some of the compressed data (see "Data-Unloading Functions," for more information on the data-unloading structure). If you have not provided a data-unloading function, set this parameter to nil . In this case, the compressor writes the entire compressed image into the memory location specified by the data parameter.

progressProc

Points to a progress function structure. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions" for more information about progress functions). If you have not provided a progress function, set this parameter to nil . If you pass a value of -1, you obtain a standard progress function.

desc

Contains a handle that is to receive a formatted image description structure. The Image Compression Manager resizes this handle for the returned image description structure. Your application should store this image description with the compressed image data.

data

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by the GetMaxCompressionSize function (described on GetMaxCompressionSize ). If there is not sufficient memory to store the compressed image, you may choose to write the compressed data to mass storage during the compression operation. Use the flushProc parameter to identify your data-unloading function to the compressor. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that handle with this parameter. (See Inside Macintosh: Memory for details on StripAddress .)

The Image Compression Manager places the actual size of the compressed image into the dataSize field of the image description structure referred to by the desc parameter.

DecompressImage

The DecompressImage function allows your application to decompress a single-frame image into a pixel map structure. If you call this function when you have a picture open, the Image Compression Manager inserts the compressed image data into the picture.

pascal OSErr DecompressImage (Ptr data,
                                         ImageDescriptionHandle desc,
                                         PixMapHandle dst, const Rect *srcRect,
                                         const Rect *dstRect, short mode,
                                         RgnHandle mask);


data

Points to the compressed image data. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that handle with this parameter.

desc

Contains a handle to the image description structure that describes the compressed image.

dst

Contains a handle to the pixel map where the decompressed image is to be displayed. Set the current graphics port to the port that contains this pixel map.

srcRect

Contains a pointer to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by (0,0) and ((**desc).width,(**desc).height) . If you want to decompress the entire source image, set this parameter to nil . If the parameter is nil , the rectangle is set to the rectangle structure of the image description structure.

dstRect

Contains a pointer to the rectangle into which the decompressed image is to be loaded. The compressor scales the source image to fit into this destination rectangle.

mode

Specifies the transfer mode for the operation. The Image Compression Manager supports the same transfer modes supported by QuickDraw's CopyBits routine.

mask

Contains a handle to a clipping region in the destination coordinate system. If specified, the compressor applies this mask to the destination image. If you do not want to mask bits in the destination, set this parameter to nil .

FDecompressImage

Like the DecompressImage function, the FDecompressImage function allows your application to decompress a single-frame image into a pixel map ( PixMap ). This function gives your application greater control over the parameters that guide the decompression operation. If you find that you do not need this level of control, use the DecompressImage function, described in the previous section.

pascal OSErr FDecompressImage (Ptr data,
                                         ImageDescriptionHandle desc,
                                         PixMapHandle dst,
                                         const Rect *srcRect,
                                         MatrixRecordPtr matrix,
                                         short mode, RgnHandle mask,
                                         PixMapHandle matte,
                                         const Rect *matteRect,
                                         CodecQ accuracy,
                                         DecompressorComponent codec,
                                         long bufferSize,
                                         ICMDataProcRecordPtr dataProc,
                                         ICMProgressProcRecordPtr progressProc);


data

Points to the compressed image data. If the entire compressed image cannot be stored at this location, your application may provide a data-loading function (see the discussion of the dataProc parameter to this function). This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that handle with this parameter. (See Inside Macintosh: Memory for details on StripAddress .)

desc

Contains a handle to the image description structure that describes the compressed image.

dst

Contains a handle to the pixel map where the decompressed image is to be displayed. Set the current graphics port to the port that contains this pixel map.

srcRect

Contains a pointer to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by (0,0) and ((**desc).width,(**desc).height) . If you want to decompress the entire source image, set this parameter to nil . If the parameter is nil , the rectangle is set to the rectangle structure of the image description structure.

matrix

Points to a matrix structure that specifies how to transform the image during decompression. You can use the matrix structure to translate or scale the image during decompression. If you do not want to apply such effects, set the matrix parameter to nil . See the chapter "Movie Toolbox" in this book for more information about matrix operations.

mode

Specifies the transfer mode for the operation. The Image Compression Manager supports the same transfer modes supported by QuickDraw's CopyBits routine (described in Inside Macintosh: Imaging ).

mask

Contains a handle to a clipping region in the destination coordinate system. If specified, the decompressor applies this mask to the destination image. If you do not want to mask bits in the destination, set this parameter to nil .

matte

Contains a handle to a pixel map that contains a blend matte. You can use the blend matte to cause the decompressed image to be blended into the destination pixel map. The matte can be defined at any supported pixel depth--the matte depth need not correspond to the source or destination depths. However, the matte must be in the coordinate system of the source image. If you do not want to apply a blend matte, set this parameter to nil .

matteRect

Contains a pointer to a rectangle defining a portion of the blend matte to apply. If you do not want to use the entire matte referred to by the matte parameter, use this parameter to specify a rectangle within that matte. If specified, this rectangle must be the same size as the rectangle specified by the srcRect parameter. If you want to use the entire matte, or if you are not providing a blend matte, set this parameter to nil .

accuracy

Specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. See "Compression Quality Constants," for valid values. (For a good display of still images, you should specify at least the codecHighQuality constant.)

codec

Contains a compressor identifier. Specify a particular decompressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first decompressor of the specified type

bestSpeedCodec

Choose the fastest decompressor of the specified type

bestFidelityCodec

Choose the most accurate decompressor of the specified type

bestCompressionCodec

Choose the decompressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

If you set the codec parameter to anyCodec , the Image Compression Manager chooses the first decompressor it finds of the specified type.

bufferSize

Specifies the size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.

dataProc

Points to a data-loading function structure. If there is not enough memory to store the compressed image, the compressor calls a function you provide that loads more compressed data (see "Data-Loading Functions" for more information about data-loading functions). If you have not provided a data-loading function, set this parameter to nil . In this case, the compressor expects that the entire compressed image is in the memory location specified by the data parameter.

progressProc

Points to a progress function structure. During the decompression operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions" for more information about progress functions). If you have not provided a progress function, set this parameter to nil . If you pass a value of -1, you obtain a standard progress function.

ConvertImage

The ConvertImage function allows your application to convert the format of a compressed image. This function is essentially equivalent to decompressing and recompressing the image.

pascal OSErr ConvertImage (ImageDescriptionHandle srcDD,
                                         Ptr srcData, short colorDepth,
                                         CTabHandle ctable, CodecQ accuracy,
                                         CodecQ quality, CodecType cType,
                                          CodecComponent codec,
                                         ImageDescriptionHandle dstDD,
                                         Ptr dstData);


srcDD

Contains a handle to the image description structure that describes the compressed image.

srcData

Points to the compressed image data. This pointer must contain a 32-bit clean address.

colorDepth

Specifies the depth at which the recompressed image is likely to be viewed. Decompressors may use this as an indication of the color or grayscale resolution of the compressed image. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function (see "Getting Information About Compressor Components" for more information on the GetCodecInfo function).

ctable

Contains a handle to a custom color lookup table. Your program may use this parameter to indicate a custom color lookup table to be used with this image. If the value of the colorDepth parameter is less than or equal to 8 and the custom color lookup table is different from that of the source pixel map (that is, the ctSeed field values differ in the two pixel maps), the compressor remaps the colors of the image to the custom colors. If you set the colorDepth parameter to 16, 24, or 32, the compressor stores the custom color table with the compressed image. The compressor may use the table to specify the best colors to use when displaying the image at lower bit depths. The compressor ignores the ctable parameter when colorDepth is set to 33, 34, 36, or 40. If you set this parameter to nil , the compressor uses the color lookup table from the source image description structure.

accuracy

Specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. See "Compression Quality Constants" for valid values. (For a good display of still images, you should specify at least the codecHighQuality constant.)

quality

Specifies the desired compressed image quality. See "Compression Quality Constants" for valid values. Use the following value:

codecHighQuality

Specifies high-quality image reproduction. This value should correspond to the highest image quality that can be achieved with reasonable performance.

cType

Specifies a compressor type. You must set this parameter to a valid compressor type. See Table 3 for a list of the available compressor types.

codec

Contains a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCodec

Choose the most accurate compressor of the specified type

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

If you set the codec parameter to anyCodec , the Image Compression Manager chooses the first compressor it finds of the specified type.

dstDD

Contains a handle that is to receive a formatted image description structure. The Image Compression Manager resizes this handle for the returned image description structure. Your application should store this image description with the compressed image data.

dstData

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by the GetMaxCompressionSize function (described on GetMaxCompressionSize ). The Image Compression Manager places the actual size of the compressed image into the dataSize field of the image description referred to by the dstDD parameter. This pointer must contain a 32-bit clean address.

TrimImage

The TrimImage function adjusts a compressed image to the boundaries defined by a rectangle specified by your application.

pascal OSErr TrimImage (ImageDescriptionHandle desc, Ptr inData,
                                         long inBufferSize,
                                         ICMDataProcRecordPtr dataProc,
                                         Ptr outData, long outBufferSize,
                                         ICMFlushProcRecordPtr flushProc,
                                         Rect *trimRect,
                                         ICMProgressProcRecordPtr progressProc);


desc

Contains a handle to the image description structure that describes the compressed image. On return from TrimImage , the compressor updates this image description to refer to the resized image.

inData

Points to the compressed image data. If the entire compressed image cannot be stored at this location, your application may provide a data-loading function (see the discussion of the dataProc parameter to this function). This pointer must contain a 32-bit clean address.

inBufferSize

Specifies the size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, this parameter is ignored.

dataProc

Points to a data-loading function structure. If there is not enough memory to store the compressed image, the compressor calls a function you provide that loads more compressed data (see "Data-Loading Functions," for more information about data-loading function structures). If you have not provided a data-loading function, set this parameter to nil . In this case, the compressor expects that the entire compressed image is in the memory location specified by the inData parameter.

outData

Points to a buffer to receive the trimmed image. Your application should create this destination buffer at least as large as the source image. If there is not sufficient memory to store the compressed image, you may choose to write the compressed data to mass storage during the compression operation. Use the flushProc parameter to identify your data-unloading function to the compressor. This pointer must contain a 32-bit clean address.

The Image Compression Manager places the actual size of the resulting image into the dataSize field of the image description structure referred to by the desc parameter.

outBufferSize

Specifies the size of the buffer to be used by the data-unloading function specified by the flushProc parameter. If you have not specified a data-unloading function, this parameter is ignored.

flushProc

Points to a data-unloading function structure. If there is not enough memory to store the compressed image, the compressor calls a function you provide that unloads some of the compressed data (see "Data-Unloading Functions," for more information on the data-unloading structure). If you have not provided a data-unloading function, set this parameter to nil . In this case, the compressor writes the entire compressed image into the memory location specified by the data parameter.

trimRect

Contains a pointer to a rectangle that defines the desired image dimensions. Upon return to your application, the compressor adjusts the rectangle values so that they refer to the same rectangle in the result image (this is necessary whenever data is removed from the beginning or from the left side of the image).

progressProc

Points to a progress function structure. During the operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions" for more information about progress functions). If you have not provided a progress function, set this parameter to nil . If you pass a value of -1, you obtain a standard progress function .

SetImageDescriptionCTable

Your application may use the SetImageDescriptionCTable function to update the custom color table for an image. The Image Compression Manager copies the custom color table for an image into the appropriate image description structure. This function does not change the image data, just the color table.

pascal OSErr SetImageDescriptionCTable
                                         (ImageDescriptionHandle desc,
                                         CTabHandle ctable);


desc

Contains a handle to the appropriate image description structure. The SetImageDescriptionCTable function updates the size of the image description to accommodate the new color table and removes the old color table, if one is present.

ctable

Contains a handle to the new color table. The SetImageDescriptionCTable function loads this color table into the image description referred to by the desc parameter. Set this parameter to nil to remove a color table.

GetImageDescriptionCTable

Your application may use the GetImageDescriptionCTable function to set the custom color table for an image.

pascal OSErr GetImageDescriptionCTable
                                         (ImageDescriptionHandle desc,
                                          CTabHandle *ctable);


desc

Contains a handle to the appropriate image description structure.

ctable

Contains a pointer to a field that is to receive a color table handle. The GetImageDescriptionCTable function returns the color table for the image described by the image description structure that is referred to by the desc parameter. The function correctly sizes the handle for the color table it returns.